<?php

/**
 * IRaiseCache interface
 * A caching mechanism for load speed up
 *
 * @author Sam-Mauris Yong <hellclanner at live dot com>
 * @license http://www.opensource.org/licenses/bsd-license New BSD License
 * @package Raise.Core.Caching
 * @since 1.2
 */
interface IRaiseCache {

    /**
     * Get or set the period of time that this cache should live
     * @param RaiseTimeSpan $l (optional) If this parameter is passed in, it will set the new value.
     * @return RaiseTimeSpan
     */
    public function life($l = null);

    /**
     * Get or set the unique identifier of this cache
     * @param string $i (optional) If this parameter is passed in, it will set the new value.
     * @return string
     */
    public function id($i = null);

    /**
     * Get the expiry RaiseDateTime of this cache
     * @return RaiseDateTime
     */
    public function expiry();

    /**
     * Query if the cache is still fresh
     * @return boolean TRUE if the query is still fresh, FALSE otherwise
     */
    public function query();

    /**
     * Save the cache with a fresher content
     * @param string $c Content to save
     */
    public function save($c);

    /**
     * Load the cache if cache is fresh
     * @return string The cache. If the cache is not fresh, NULL will be returned.
     */
    public function load();

    /**
     * Delete the cache, whether or not the cache is fresh.
     */
    public function delete();

    /**
     * Clear off all the caches in this cache storage,
     * whether the cache is still fresh or not.
     * @static
     */
    public static function clear();

}
